<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Module: ActionController::Caching::Pages</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <meta http-equiv="Content-Script-Type" content="text/javascript" />
  <link rel="stylesheet" href="../../.././rdoc-style.css" type="text/css" media="screen" />
  <script type="text/javascript">
  // <![CDATA[

  function popupCode( url ) {
    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  }

  function toggleCode( id ) {
    if ( document.getElementById )
      elem = document.getElementById( id );
    else if ( document.all )
      elem = eval( "document.all." + id );
    else
      return false;

    elemStyle = elem.style;
    
    if ( elemStyle.display != "block" ) {
      elemStyle.display = "block"
    } else {
      elemStyle.display = "none"
    }

    return true;
  }
  
  // Make codeblocks hidden by default
  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  
  // ]]>
  </script>

</head>
<body>



    <div id="classHeader">
        <table class="header-table">
        <tr class="top-aligned-row">
          <td><strong>Module</strong></td>
          <td class="class-name-in-header">ActionController::Caching::Pages</td>
        </tr>
        <tr class="top-aligned-row">
            <td><strong>In:</strong></td>
            <td>
                <a href="../../../files/vendor/rails/actionpack/lib/action_controller/caching/pages_rb.html">
                vendor/rails/actionpack/lib/action_controller/caching/pages.rb
                </a>
        <br />
            </td>
        </tr>

        </table>
    </div>
  <!-- banner header -->

  <div id="bodyContent">



  <div id="contextContent">

    <div id="description">
      <p>
Page caching is an approach to caching where the entire action output of is
stored as a HTML file that the web server can serve without going through
Action Pack. This is the fastest way to cache your content as opposed to
going dynamically through the process of generating the content.
Unfortunately, this incredible speed-up is only available to stateless
pages where all visitors are treated the same. Content management systems
&#8212; including weblogs and wikis &#8212; have many pages that are a
great fit for this approach, but account-based systems where people log in
and manipulate their own data are often less likely candidates.
</p>
<p>
Specifying which actions to cache is done through the <tt>caches_page</tt>
class method:
</p>
<pre>
  class WeblogController &lt; ActionController::Base
    caches_page :show, :new
  end
</pre>
<p>
This will generate cache files such as <tt>weblog/show/5.html</tt> and
<tt>weblog/new.html</tt>, which match the URLs used to trigger the dynamic
generation. This is how the web server is able pick up a cache file when it
exists and otherwise let the request pass on to Action Pack to generate it.
</p>
<p>
Expiration of the cache is handled by deleting the cached file, which
results in a lazy regeneration approach where the cache is not restored
before another hit is made against it. The API for doing so mimics the
options from <tt>url_for</tt> and friends:
</p>
<pre>
  class WeblogController &lt; ActionController::Base
    def update
      List.update(params[:list][:id], params[:list])
      expire_page :action =&gt; &quot;show&quot;, :id =&gt; params[:list][:id]
      redirect_to :action =&gt; &quot;show&quot;, :id =&gt; params[:list][:id]
    end
  end
</pre>
<p>
Additionally, you can expire caches using Sweepers that act on changes in
the model to determine when a cache is supposed to be expired.
</p>
<h2>Setting the cache directory</h2>
<p>
The cache directory should be the document root for the web server and is
set using <tt>Base.page_cache_directory = &quot;/document/root&quot;</tt>.
For <a href="../../Rails.html">Rails</a>, this directory has already been
set to <a href="../../Rails.html#M001795">Rails.public_path</a> (which is
usually set to <tt>RAILS_ROOT + &quot;/public&quot;</tt>). Changing this
setting can be useful to avoid naming conflicts with files in
<tt>public/</tt>, but doing so will likely require configuring your web
server to look in the new location for cached files.
</p>
<h2>Setting the cache extension</h2>
<p>
Most <a href="../../Rails.html">Rails</a> requests do not have an
extension, such as <tt>/weblog/new</tt>. In these cases, the page caching
mechanism will add one in order to make it easy for the cached files to be
picked up properly by the web server. By default, this cache extension is
<tt>.html</tt>. If you want something else, like <tt>.php</tt> or
<tt>.shtml</tt>, just set Base.page_cache_extension. In cases where a
request already has an extension, such as <tt>.xml</tt> or <tt>.rss</tt>,
page caching will not add an extension. This allows it to work well with
RESTful apps.
</p>

    </div>


   </div>

    <div id="method-list">
      <h3 class="section-bar">Methods</h3>

      <div class="name-list">
      <a href="#M000874">cache_page</a>&nbsp;&nbsp;
      <a href="#M000873">expire_page</a>&nbsp;&nbsp;
      </div>
    </div>

  </div>


    <!-- if includes -->

    <div id="section">

    <div id="class-list">
      <h3 class="section-bar">Classes and Modules</h3>

      Module <a href="Pages/ClassMethods.html" class="link">ActionController::Caching::Pages::ClassMethods</a><br />

    </div>




      


    <!-- if method_list -->
    <div id="methods">
      <h3 class="section-bar">Public Instance methods</h3>

      <div id="method-M000874" class="method-detail">
        <a name="M000874"></a>

        <div class="method-heading">
          <a href="#M000874" class="method-signature">
          <span class="method-name">cache_page</span><span class="method-args">(content = nil, options = nil)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Manually cache the <tt>content</tt> in the key determined by
<tt>options</tt>. If no content is provided, the contents of response.body
is used If no options are provided, the requested url is used. Example:
</p>
<pre>
  cache_page &quot;I'm the cached content&quot;, :controller =&gt; &quot;lists&quot;, :action =&gt; &quot;show&quot;
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000874-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000874-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/caching/pages.rb, line 133</span>
133:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">cache_page</span>(<span class="ruby-identifier">content</span> = <span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">options</span> = <span class="ruby-keyword kw">nil</span>)
134:         <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">perform_caching</span> <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-identifier">caching_allowed</span>
135: 
136:         <span class="ruby-identifier">path</span> = <span class="ruby-keyword kw">case</span> <span class="ruby-identifier">options</span>
137:           <span class="ruby-keyword kw">when</span> <span class="ruby-constant">Hash</span>
138:             <span class="ruby-identifier">url_for</span>(<span class="ruby-identifier">options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">:only_path</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword kw">true</span>, <span class="ruby-identifier">:skip_relative_url_root</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword kw">true</span>, <span class="ruby-identifier">:format</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">params</span>[<span class="ruby-identifier">:format</span>]))
139:           <span class="ruby-keyword kw">when</span> <span class="ruby-constant">String</span>
140:             <span class="ruby-identifier">options</span>
141:           <span class="ruby-keyword kw">else</span>
142:             <span class="ruby-identifier">request</span>.<span class="ruby-identifier">path</span>
143:         <span class="ruby-keyword kw">end</span>
144: 
145:         <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">cache_page</span>(<span class="ruby-identifier">content</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">response</span>.<span class="ruby-identifier">body</span>, <span class="ruby-identifier">path</span>)
146:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000873" class="method-detail">
        <a name="M000873"></a>

        <div class="method-heading">
          <a href="#M000873" class="method-signature">
          <span class="method-name">expire_page</span><span class="method-args">(options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Expires the page that was cached with the <tt>options</tt> as a key.
Example:
</p>
<pre>
  expire_page :controller =&gt; &quot;lists&quot;, :action =&gt; &quot;show&quot;
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000873-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000873-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/caching/pages.rb, line 114</span>
114:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">expire_page</span>(<span class="ruby-identifier">options</span> = {})
115:         <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">perform_caching</span>
116: 
117:         <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">options</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">Hash</span>)
118:           <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:action</span>].<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">Array</span>)
119:             <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:action</span>].<span class="ruby-identifier">dup</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">action</span><span class="ruby-operator">|</span>
120:               <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">expire_page</span>(<span class="ruby-identifier">url_for</span>(<span class="ruby-identifier">options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">:only_path</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword kw">true</span>, <span class="ruby-identifier">:skip_relative_url_root</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword kw">true</span>, <span class="ruby-identifier">:action</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">action</span>)))
121:             <span class="ruby-keyword kw">end</span>
122:           <span class="ruby-keyword kw">else</span>
123:             <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">expire_page</span>(<span class="ruby-identifier">url_for</span>(<span class="ruby-identifier">options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">:only_path</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword kw">true</span>, <span class="ruby-identifier">:skip_relative_url_root</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword kw">true</span>)))
124:           <span class="ruby-keyword kw">end</span>
125:         <span class="ruby-keyword kw">else</span>
126:           <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">expire_page</span>(<span class="ruby-identifier">options</span>)
127:         <span class="ruby-keyword kw">end</span>
128:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>


    </div>


  </div>


<div id="validator-badges">
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>

</body>
</html>